Skip to content

Optimize SPFx release pages for agentic upgrade workflows#10921

Open
garrytrinder wants to merge 12 commits into
SharePoint:mainfrom
garrytrinder:garrytrinder-replace-cli-upgrade-tips-with-warning
Open

Optimize SPFx release pages for agentic upgrade workflows#10921
garrytrinder wants to merge 12 commits into
SharePoint:mainfrom
garrytrinder:garrytrinder-replace-cli-upgrade-tips-with-warning

Conversation

@garrytrinder

@garrytrinder garrytrinder commented Jun 23, 2026

Copy link
Copy Markdown
Contributor

Summary

Updates all SPFx release notes pages and the Gulp-to-Heft migration guide to improve upgrade guidance by directing developers to use CLI for Microsoft 365.

Changes

All release pages (40 files)

  • Replaced shared TIP (recommending CLI for Microsoft 365) with a WARNING explaining that upgrading requires changes across package versions, build configuration, and toolchain settings — manually updating package.json alone will cause build failures.
  • Added a version-specific TIP with the exact npx command to run m365 spfx project upgrade --toVersion <version> for each release page.
  • Added the community disclaimer NOTE (existing pnp-o365cli snippet) clarifying CLI for Microsoft 365 is open-source with no Microsoft SLA.
  • Renamed snippet from spfx-release-upgrade-tip.mdspfx-release-upgrade-warning.md to reflect its new content.

docs/spfx/release-1.22.0.md

  • Restructured the upgrade section: warning/tip/disclaimer appear first, followed by a link to the migration guide.
  • Removed redundant "See more details" bullet under "Transitioning from Gulp-based toolchain".

docs/spfx/toolchain/migrate-gulptoolchain-hefttoolchain.md

  • Complete rewrite: replaced the detailed manual step-by-step migration instructions with:
    • An overview of what changes during the migration (packages, TypeScript config, build scripts, ESLint rules, configuration files, removed files, production deps).
    • Direction to use m365 spfx project upgrade to generate the full set of changes automatically.
    • A verification step.

garrytrinder and others added 3 commits June 23, 2026 14:28
Replace the TIP recommending CLI for Microsoft 365 for upgrades with a
WARNING explaining that upgrading from a previous minor version requires
changes across package versions, build configuration files, and toolchain
settings.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add a TIP after the WARNING on each release page showing the exact
npx command to run for upgrading to that specific version using
CLI for Microsoft 365's spfx project upgrade command.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…warning

The snippet now contains a WARNING, so the filename should reflect that.
Updated all references across release pages and the template.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit 90e3802:

❌ Validation status: errors

Please follow instructions here which may help to resolve issue.

File Status Preview URL Details
❌Error Details

  • [Error: CannotMergeCommit] Cannot merge commit 90e3802ba785fe4694eefe561312d4f0257535a3 in branch garrytrinder-replace-cli-upgrade-tips-with-warning of repository https://github.com/garrytrinder/sp-dev-docs into branch main (commit f082db5f60f3102a1114a9e09bcde4083fcec8fe). Please follow this documentation: https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/ to use git.exe to resolve you content conflicts locally and then push to remote.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit 90e3802:

❌ Validation status: errors

Please follow instructions here which may help to resolve issue.

File Status Preview URL Details
❌Error Details

  • [Error: CannotMergeCommit] Cannot merge commit 90e3802ba785fe4694eefe561312d4f0257535a3 in branch garrytrinder-replace-cli-upgrade-tips-with-warning of repository https://github.com/garrytrinder/sp-dev-docs into branch main (commit f082db5f60f3102a1114a9e09bcde4083fcec8fe). Please follow this documentation: https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/ to use git.exe to resolve you content conflicts locally and then push to remote.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

garrytrinder and others added 4 commits June 23, 2026 14:55
Replace the TIP recommending CLI for Microsoft 365 for upgrades with a
WARNING explaining that upgrading from a previous minor version requires
changes across package versions, build configuration files, and toolchain
settings.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add a TIP after the WARNING on each release page showing the exact
npx command to run for upgrading to that specific version using
CLI for Microsoft 365's spfx project upgrade command.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…warning

The snippet now contains a WARNING, so the filename should reflect that.
Updated all references across release pages and the template.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@garrytrinder garrytrinder force-pushed the garrytrinder-replace-cli-upgrade-tips-with-warning branch from 90e3802 to 1dd128e Compare June 23, 2026 13:56
@learn-build-service-prod

Copy link
Copy Markdown
Contributor

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit 1dd128e:

⚠️ Validation status: warnings

File Status Preview URL Details
docs/spfx/release-1.15.2.md ⚠️Warning View Details
docs/spfx/release-0.0.0.md.template ✅Succeeded
docs/spfx/release-1.0.0.md ✅Succeeded View
docs/spfx/release-1.1.0.md ✅Succeeded View
docs/spfx/release-1.10.0.md ✅Succeeded View
docs/spfx/release-1.11.0.md ✅Succeeded View
docs/spfx/release-1.12.1.md ✅Succeeded View
docs/spfx/release-1.13.0.md ✅Succeeded View
docs/spfx/release-1.13.1.md ✅Succeeded View
docs/spfx/release-1.14.0.md ✅Succeeded View
docs/spfx/release-1.15.0.md ✅Succeeded View
docs/spfx/release-1.16.0.md ✅Succeeded View
docs/spfx/release-1.16.1.md ✅Succeeded View
docs/spfx/release-1.17.0.md ✅Succeeded View
docs/spfx/release-1.17.1.md ✅Succeeded View
docs/spfx/release-1.17.2.md ✅Succeeded View
docs/spfx/release-1.17.3.md ✅Succeeded View
docs/spfx/release-1.17.4.md ✅Succeeded View
docs/spfx/release-1.18.0.md ✅Succeeded View
docs/spfx/release-1.18.1.md ✅Succeeded View
docs/spfx/release-1.18.2.md ✅Succeeded View
docs/spfx/release-1.19.0.md ✅Succeeded View
docs/spfx/release-1.20.0.md ✅Succeeded View
docs/spfx/release-1.21.0.md ✅Succeeded View
docs/spfx/release-1.21.1.md ✅Succeeded View

This comment lists only the first 25 files in the pull request.

docs/spfx/release-1.15.2.md

  • Line 62, Column 44: [Warning: bookmark-not-found - See documentation] Cannot find bookmark '#requesting-permissions-to-azure-ad-applications-in-another-tenant' in 'spfx/use-aadhttpclient.md', did you mean '#requesting-permissions-to-entra-id-applications-in-another-tenant'?

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

Include the existing pnp-o365cli NOTE snippet after the upgrade TIP
on each SPFx release page and the template.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@learn-build-service-prod

Copy link
Copy Markdown
Contributor

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit f2ddca8:

⚠️ Validation status: warnings

File Status Preview URL Details
docs/spfx/release-1.15.2.md ⚠️Warning View Details
docs/spfx/release-0.0.0.md.template ✅Succeeded
docs/spfx/release-1.0.0.md ✅Succeeded View
docs/spfx/release-1.1.0.md ✅Succeeded View
docs/spfx/release-1.10.0.md ✅Succeeded View
docs/spfx/release-1.11.0.md ✅Succeeded View
docs/spfx/release-1.12.1.md ✅Succeeded View
docs/spfx/release-1.13.0.md ✅Succeeded View
docs/spfx/release-1.13.1.md ✅Succeeded View
docs/spfx/release-1.14.0.md ✅Succeeded View
docs/spfx/release-1.15.0.md ✅Succeeded View
docs/spfx/release-1.16.0.md ✅Succeeded View
docs/spfx/release-1.16.1.md ✅Succeeded View
docs/spfx/release-1.17.0.md ✅Succeeded View
docs/spfx/release-1.17.1.md ✅Succeeded View
docs/spfx/release-1.17.2.md ✅Succeeded View
docs/spfx/release-1.17.3.md ✅Succeeded View
docs/spfx/release-1.17.4.md ✅Succeeded View
docs/spfx/release-1.18.0.md ✅Succeeded View
docs/spfx/release-1.18.1.md ✅Succeeded View
docs/spfx/release-1.18.2.md ✅Succeeded View
docs/spfx/release-1.19.0.md ✅Succeeded View
docs/spfx/release-1.20.0.md ✅Succeeded View
docs/spfx/release-1.21.0.md ✅Succeeded View
docs/spfx/release-1.21.1.md ✅Succeeded View

This comment lists only the first 25 files in the pull request.

docs/spfx/release-1.15.2.md

  • Line 64, Column 44: [Warning: bookmark-not-found - See documentation] Cannot find bookmark '#requesting-permissions-to-azure-ad-applications-in-another-tenant' in 'spfx/use-aadhttpclient.md', did you mean '#requesting-permissions-to-entra-id-applications-in-another-tenant'?

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

Update anchor from Azure AD to Entra ID to match the renamed heading
in use-aadhttpclient.md.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@learn-build-service-prod

Copy link
Copy Markdown
Contributor

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit 957878f:

✅ Validation status: passed

File Status Preview URL Details
docs/spfx/release-0.0.0.md.template ✅Succeeded
docs/spfx/release-1.0.0.md ✅Succeeded View
docs/spfx/release-1.1.0.md ✅Succeeded View
docs/spfx/release-1.10.0.md ✅Succeeded View
docs/spfx/release-1.11.0.md ✅Succeeded View
docs/spfx/release-1.12.1.md ✅Succeeded View
docs/spfx/release-1.13.0.md ✅Succeeded View
docs/spfx/release-1.13.1.md ✅Succeeded View
docs/spfx/release-1.14.0.md ✅Succeeded View
docs/spfx/release-1.15.0.md ✅Succeeded View
docs/spfx/release-1.15.2.md ✅Succeeded View
docs/spfx/release-1.16.0.md ✅Succeeded View
docs/spfx/release-1.16.1.md ✅Succeeded View
docs/spfx/release-1.17.0.md ✅Succeeded View
docs/spfx/release-1.17.1.md ✅Succeeded View
docs/spfx/release-1.17.2.md ✅Succeeded View
docs/spfx/release-1.17.3.md ✅Succeeded View
docs/spfx/release-1.17.4.md ✅Succeeded View
docs/spfx/release-1.18.0.md ✅Succeeded View
docs/spfx/release-1.18.1.md ✅Succeeded View
docs/spfx/release-1.18.2.md ✅Succeeded View
docs/spfx/release-1.19.0.md ✅Succeeded View
docs/spfx/release-1.20.0.md ✅Succeeded View
docs/spfx/release-1.21.0.md ✅Succeeded View
docs/spfx/release-1.21.1.md ✅Succeeded View

This comment lists only the first 25 files in the pull request.
For more details, please refer to the build report.

These pages were missing the warning snippet, version-specific TIP,
and community disclaimer that were added to all other release pages.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@learn-build-service-prod

Copy link
Copy Markdown
Contributor

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit c9853a9:

💡 Validation status: suggestions

File Status Preview URL Details
docs/spfx/release-1.22.0.md 💡Suggestion View Details
docs/spfx/release-0.0.0.md.template ✅Succeeded
docs/spfx/release-1.0.0.md ✅Succeeded View
docs/spfx/release-1.1.0.md ✅Succeeded View
docs/spfx/release-1.10.0.md ✅Succeeded View
docs/spfx/release-1.11.0.md ✅Succeeded View
docs/spfx/release-1.12.1.md ✅Succeeded View
docs/spfx/release-1.13.0.md ✅Succeeded View
docs/spfx/release-1.13.1.md ✅Succeeded View
docs/spfx/release-1.14.0.md ✅Succeeded View
docs/spfx/release-1.15.0.md ✅Succeeded View
docs/spfx/release-1.15.2.md ✅Succeeded View
docs/spfx/release-1.16.0.md ✅Succeeded View
docs/spfx/release-1.16.1.md ✅Succeeded View
docs/spfx/release-1.17.0.md ✅Succeeded View
docs/spfx/release-1.17.1.md ✅Succeeded View
docs/spfx/release-1.17.2.md ✅Succeeded View
docs/spfx/release-1.17.3.md ✅Succeeded View
docs/spfx/release-1.17.4.md ✅Succeeded View
docs/spfx/release-1.18.0.md ✅Succeeded View
docs/spfx/release-1.18.1.md ✅Succeeded View
docs/spfx/release-1.18.2.md ✅Succeeded View
docs/spfx/release-1.19.0.md ✅Succeeded View
docs/spfx/release-1.20.0.md ✅Succeeded View
docs/spfx/release-1.21.0.md ✅Succeeded View

This comment lists only the first 25 files in the pull request.

docs/spfx/release-1.22.0.md

  • Line 12, Column 3: [Suggestion: docs-link-absolute - See documentation] Absolute link 'https://learn.microsoft.com/javascript/api/overview/sharepoint?view=sp-typescript-latest' will be broken in isolated environments. Replace with a relative link.
  • Line 12, Column 3: [Suggestion: preserve-view-not-set - See documentation] You've pinned this link to a specific version of content with the view parameter. It's recommended not to pin a version unless that version is A) not the default view and B) the context is about that version specifically. To proceed with pinning a version add the &preserve-view=true to the URL. Otherwise, remove the view parameter. URL: https://learn.microsoft.com/javascript/api/overview/sharepoint?view=sp-typescript-latest

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

@garrytrinder garrytrinder marked this pull request as draft June 24, 2026 15:42
@garrytrinder

Copy link
Copy Markdown
Contributor Author

Set to draft, found some inconsistencies that I need to investigate.

- Update TIP description across all release pages to mention the
  single script output
- Rewrite migrate-gulptoolchain-hefttoolchain.md to direct users to
  CLI for Microsoft 365 instead of manual step-by-step instructions
- Update release-1.22.0 upgrade section to reference migration page
  after the warning/tip/disclaimer block
- Remove redundant 'See more details' section from release-1.22.0

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@learn-build-service-prod

Copy link
Copy Markdown
Contributor

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit 520e4c6:

💡 Validation status: suggestions

File Status Preview URL Details
docs/spfx/release-1.22.0.md 💡Suggestion View Details
docs/spfx/release-0.0.0.md.template ✅Succeeded
docs/spfx/release-1.0.0.md ✅Succeeded View
docs/spfx/release-1.1.0.md ✅Succeeded View
docs/spfx/release-1.10.0.md ✅Succeeded View
docs/spfx/release-1.11.0.md ✅Succeeded View
docs/spfx/release-1.12.1.md ✅Succeeded View
docs/spfx/release-1.13.0.md ✅Succeeded View
docs/spfx/release-1.13.1.md ✅Succeeded View
docs/spfx/release-1.14.0.md ✅Succeeded View
docs/spfx/release-1.15.0.md ✅Succeeded View
docs/spfx/release-1.15.2.md ✅Succeeded View
docs/spfx/release-1.16.0.md ✅Succeeded View
docs/spfx/release-1.16.1.md ✅Succeeded View
docs/spfx/release-1.17.0.md ✅Succeeded View
docs/spfx/release-1.17.1.md ✅Succeeded View
docs/spfx/release-1.17.2.md ✅Succeeded View
docs/spfx/release-1.17.3.md ✅Succeeded View
docs/spfx/release-1.17.4.md ✅Succeeded View
docs/spfx/release-1.18.0.md ✅Succeeded View
docs/spfx/release-1.18.1.md ✅Succeeded View
docs/spfx/release-1.18.2.md ✅Succeeded View
docs/spfx/release-1.19.0.md ✅Succeeded View
docs/spfx/release-1.20.0.md ✅Succeeded View
docs/spfx/release-1.21.0.md ✅Succeeded View

This comment lists only the first 25 files in the pull request.

docs/spfx/release-1.22.0.md

  • Line 12, Column 3: [Suggestion: docs-link-absolute - See documentation] Absolute link 'https://learn.microsoft.com/javascript/api/overview/sharepoint?view=sp-typescript-latest' will be broken in isolated environments. Replace with a relative link.
  • Line 12, Column 3: [Suggestion: preserve-view-not-set - See documentation] You've pinned this link to a specific version of content with the view parameter. It's recommended not to pin a version unless that version is A) not the default view and B) the context is about that version specifically. To proceed with pinning a version add the &preserve-view=true to the URL. Otherwise, remove the view parameter. URL: https://learn.microsoft.com/javascript/api/overview/sharepoint?view=sp-typescript-latest

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

Replace absolute learn.microsoft.com URL with relative path and remove
pinned view parameter.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@learn-build-service-prod

Copy link
Copy Markdown
Contributor

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit 1d58183:

✅ Validation status: passed

File Status Preview URL Details
docs/spfx/release-0.0.0.md.template ✅Succeeded
docs/spfx/release-1.0.0.md ✅Succeeded View
docs/spfx/release-1.1.0.md ✅Succeeded View
docs/spfx/release-1.10.0.md ✅Succeeded View
docs/spfx/release-1.11.0.md ✅Succeeded View
docs/spfx/release-1.12.1.md ✅Succeeded View
docs/spfx/release-1.13.0.md ✅Succeeded View
docs/spfx/release-1.13.1.md ✅Succeeded View
docs/spfx/release-1.14.0.md ✅Succeeded View
docs/spfx/release-1.15.0.md ✅Succeeded View
docs/spfx/release-1.15.2.md ✅Succeeded View
docs/spfx/release-1.16.0.md ✅Succeeded View
docs/spfx/release-1.16.1.md ✅Succeeded View
docs/spfx/release-1.17.0.md ✅Succeeded View
docs/spfx/release-1.17.1.md ✅Succeeded View
docs/spfx/release-1.17.2.md ✅Succeeded View
docs/spfx/release-1.17.3.md ✅Succeeded View
docs/spfx/release-1.17.4.md ✅Succeeded View
docs/spfx/release-1.18.0.md ✅Succeeded View
docs/spfx/release-1.18.1.md ✅Succeeded View
docs/spfx/release-1.18.2.md ✅Succeeded View
docs/spfx/release-1.19.0.md ✅Succeeded View
docs/spfx/release-1.20.0.md ✅Succeeded View
docs/spfx/release-1.21.0.md ✅Succeeded View
docs/spfx/release-1.21.1.md ✅Succeeded View

This comment lists only the first 25 files in the pull request.
For more details, please refer to the build report.

@garrytrinder garrytrinder marked this pull request as ready for review June 29, 2026 10:38
@garrytrinder garrytrinder changed the title Replace CLI upgrade tips with warning on SPFx release pages Optimize SPFx release pages for agentic upgrade workflows Jun 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant